// Copyright 2016 The PDFium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

// Original code copyright 2014 Foxit Software Inc. http://www.foxitsoftware.com

#ifndef CORE_FPDFAPI_FONT_CPDF_FONT_H_
#define CORE_FPDFAPI_FONT_CPDF_FONT_H_

#include <stdint.h>

#include <memory>
#include <optional>
#include <utility>
#include <vector>

#include "build/build_config.h"
#include "core/fpdfapi/parser/cpdf_dictionary.h"
#include "core/fpdfapi/parser/cpdf_stream_acc.h"
#include "core/fxcrt/fx_coordinates.h"
#include "core/fxcrt/fx_string.h"
#include "core/fxcrt/observed_ptr.h"
#include "core/fxcrt/retain_ptr.h"
#include "core/fxcrt/unowned_ptr.h"
#include "core/fxge/cfx_font.h"
当然，以下是`CPDF_Font`类中各个函数和成员变量的功能概述：

### 公有成员函数(Public Member Functions)

1. * *回调机制(Callback Mechanisms) * *

-**`class FormIface`* * :
-用于Type3字体从表单（form）获取像素的回调接口。
- **`virtual ~FormIface() = default;`** : 虚析构函数，确保派生类的析构函数被正确调用。
- **`virtual void ParseContentForType3Char(CPDF_Type3Char * pChar) = 0;`** : 解析Type3字符的内容。
- **`virtual bool HasPageObjects() const = 0;`** : 检查表单是否包含页面对象。
- **`virtual CFX_FloatRect CalcBoundingBox() const = 0;`** : 计算表单的边界框。
- **`virtual std::optional<std::pair<RetainPtr<CFX_DIBitmap>, CFX_Matrix>> GetBitmapAndMatrixFromSoleImageOfForm() const = 0;`** : 从表单中获取唯一的图像位图及其变换矩阵。

- **`class FormFactoryIface`* * :
-用于Type3字体从上层创建新表单的回调接口。
- **`virtual ~FormFactoryIface() = default;`** : 虚析构函数，确保派生类的析构函数被正确调用。
- **`virtual std::unique_ptr<FormIface> CreateForm(CPDF_Document * pDocument, RetainPtr<CPDF_Dictionary> pPageResources, RetainPtr<CPDF_Stream> pFormStream) = 0;`** : 创建一个新的表单实例。

2. * *静态方法(Static Methods) * *

-**`static constexpr uint32_t kInvalidCharCode = static_cast<uint32_t>(-1);`** : 定义无效字符码的常量值。
- **`static RetainPtr<CPDF_Font> Create(CPDF_Document * pDoc, RetainPtr<CPDF_Dictionary> pFontDict, FormFactoryIface * pFactory);`** : 创建一个新的`CPDF_Font`实例。`pFactory`仅在处理Type3字体时需要。
- **`static RetainPtr<CPDF_Font> GetStockFont(CPDF_Document * pDoc, ByteStringView fontname);`** : 获取一个预定义的标准字体。

3. * *虚方法(Virtual Methods) * *

-**字体类型检查 * *:
  -**`virtual bool IsType1Font() const;`** : 检查是否为Type1字体。
  - **`virtual bool IsTrueTypeFont() const;`** : 检查是否为TrueType字体。
  - **`virtual bool IsType3Font() const;`** : 检查是否为Type3字体。
  - **`virtual bool IsCIDFont() const;`** : 检查是否为CID字体。

  - **类型转换 * *:
  -**`virtual const CPDF_Type1Font * AsType1Font() const;`* *
  -**`virtual CPDF_Type1Font * AsType1Font();`* *
  -**`virtual const CPDF_TrueTypeFont * AsTrueTypeFont() const;`* *
  -**`virtual CPDF_TrueTypeFont * AsTrueTypeFont();`* *
  -**`virtual const CPDF_Type3Font * AsType3Font() const;`* *
  -**`virtual CPDF_Type3Font * AsType3Font();`* *
  -**`virtual const CPDF_CIDFont * AsCIDFont() const;`* *
  -**`virtual CPDF_CIDFont * AsCIDFont();`* *

  -**生命周期管理 * *:
-**`virtual void WillBeDestroyed();`** : 通知字体对象即将被销毁。

- **书写方向和兼容性 * *:
  -**`virtual bool IsVertWriting() const;`** : 检查字体是否用于垂直书写。
  - **`virtual bool IsUnicodeCompatible() const = 0;`** : 检查字体是否支持Unicode编码。

  - **字符解析 * *:
  -**`virtual uint32_t GetNextChar(ByteStringView pString, size_t * pOffset) const;`** : 从字符串中提取下一个字符，并更新偏移量。
  - **`virtual size_t CountChar(ByteStringView pString) const;`** : 计算字符串中的字符数量。
  - **`virtual void AppendChar(ByteString * buf, uint32_t charcode) const;`** : 将字符码追加到字符串中。
  - **`virtual int GlyphFromCharCode(uint32_t charcode, bool* pVertGlyph) = 0;`** : 根据字符码获取字形索引。
  - **`virtual WideString UnicodeFromCharCode(uint32_t charcode) const;`** : 根据字符码获取对应的Unicode字符串。
  - **`virtual uint32_t CharCodeFromUnicode(wchar_t Unicode) const;`** : 根据Unicode字符获取字符码。

  - **字体属性 * *:
  -**`virtual bool HasFontWidths() const;`** : 检查字体是否包含宽度信息。
  - **`virtual int GetCharWidthF(uint32_t charcode) = 0;`** : 获取指定字符码的宽度。
  - **`virtual FX_RECT GetCharBBox(uint32_t charcode) = 0;`** : 获取指定字符码的边界框。

  4. * *非虚方法(Non - Virtual Methods) * *

  -**字体信息 * *:
  -**`ByteString GetBaseFontName() const { return m_BaseFontName; }`** : 获取基础字体名称。
  - **`std: : optional<FX_Charset> GetSubstFontCharset() const;`** : 获取替代字体的字符集。
  - **`bool IsEmbedded() const { return IsType3Font() || m_pFontFile != nullptr; }`** : 检查字体是否嵌入文档。
  - **`RetainPtr<CPDF_Dictionary > GetMutableFontDict() { return m_pFontDict; }`** : 获取可修改的字体字典。
  - **`RetainPtr<const CPDF_Dictionary > GetFontDict() const { return m_pFontDict; }`** : 获取只读的字体字典。
  - **`uint32_t GetFontDictObjNum() const { return m_pFontDict->GetObjNum(); }`** : 获取字体字典的对象编号。
  - **`bool FontDictIs(const CPDF_Dictionary * pThat) const { return m_pFontDict == pThat; }`** : 检查字体字典是否是指定字典。
  - **`void ClearFontDict() { m_pFontDict = nullptr; }`** : 清空字体字典。
  - **`bool IsStandardFont() const;`** : 检查字体是否为标准字体。
  - **`bool HasFace() const { return !!m_Font.GetFace(); }`** : 检查字体是否有面（face）。

  - **度量信息 * *:
  -**`const FX_RECT & GetFontBBox() const { return m_FontBBox; }`** : 获取字体的边界框。
  - **`int GetTypeAscent() const { return m_Ascent; }`** : 获取字体的上升高度。
  - **`int GetTypeDescent() const { return m_Descent; }`** : 获取字体的下降深度。
  - **`int GetStringWidth(ByteStringView pString);`** : 获取字符串的宽度。
  - **`uint32_t FallbackFontFromCharcode(uint32_t charcode);`** : 根据字符码获取备用字体。
  - **`int FallbackGlyphFromCharcode(int fallbackFont, uint32_t charcode);`** : 根据字符码和备用字体获取字形索引。
  - **`int GetFontFlags() const { return m_Flags; }`** : 获取字体的标志。
  - **`int GetItalicAngle() const { return m_ItalicAngle; }`** : 获取字体的斜体角度。
  - **`std: : optional<int> GetFontWeight() const;`** : 获取字体的权重。

  - **其他 * *:
  -**`CPDF_Document* GetDocument() const { return m_pDocument; }`** : 获取所属的PDF文档。
  - **`CFX_Font* GetFont() { return &m_Font; }`** : 获取`CFX_Font`对象。
  - **`const CFX_Font * GetFont() const { return &m_Font; }`** : 获取只读的`CFX_Font`对象。
  - **`CFX_Font* GetFontFallback(int position);`** : 获取指定位置的备用字体。
  - **`const ByteString & GetResourceName() const { return m_ResourceName; }`** : 获取资源名称。
  - **`void SetResourceName(const ByteString & name) { m_ResourceName = name; }`** : 设置资源名称。

  ### 静态辅助函数(Static Helper Functions)

  - **`static bool UseTTCharmapMSUnicode(const RetainPtr<CFX_Face>&face)`* *
  -**`static bool UseTTCharmapMSSymbol(const RetainPtr<CFX_Face>&face)`* *
  -**`static bool UseTTCharmapMacRoman(const RetainPtr<CFX_Face>&face)`* *
  -**`static bool UseTTCharmap(const RetainPtr<CFX_Face>&face, int platform_id, int encoding_id)`* *
  -**`static const char* GetAdobeCharName(FontEncoding base_encoding, const std::vector<ByteString>&charnames, uint32_t charcode)`* *

  ### 受保护的成员函数(Protected Member Functions)

  - **`CPDF_Font(CPDF_Document * pDocument, RetainPtr<CPDF_Dictionary> pFontDict);`** : 构造函数，初始化字体对象。
  - **`~CPDF_Font() override;`** : 析构函数，清理字体对象所占用的资源。
  - **`virtual bool Load() = 0;`** : 加载字体数据，具体实现由派生类提供。
  - **`void LoadUnicodeMap() const;`** : 加载Unicode映射表。
  - **`void LoadFontDescriptor(const CPDF_Dictionary * pFontDesc);`** : 加载字体描述符。
  - **`void CheckFontMetrics();`** : 检查字体的度量信息。

  ### 私有成员变量(Private Member Variables)

  - **`UnownedPtr<CPDF_Document > const m_pDocument;`** : 存储指向PDF文档的非拥有指针。
  - **`ByteString m_ResourceName;`** : 存储字体的资源名称。
  - **`CFX_Font m_Font;`** : 存储字体对象。
  - **`std: : vector<std::unique_ptr<CFX_Font>> m_FontFallbacks;`** : 存储备用字体的向量。
  - **`RetainPtr<CPDF_StreamAcc > m_pFontFile;`** : 存储字体文件流。
  - **`RetainPtr<CPDF_Dictionary > m_pFontDict;`** : 存储字体字典。
  - **`ByteString m_BaseFontName;`** : 存储基础字体名称。
  - **`mutable std::unique_ptr<CPDF_ToUnicodeMap> m_pToUnicodeMap;`** : 存储Unicode映射表。
  - **`mutable bool m_bToUnicodeLoaded = false;`** : 标记Unicode映射表是否已加载。
  - **`bool m_bWillBeDestroyed = false;`** : 标记字体对象是否即将被销毁。
  - **`int m_Flags = 0;`** : 存储字体的标志。
  - **`int m_StemV = 0;`** : 存储字体的垂直笔画宽度。
  - **`int m_Ascent = 0;`** : 存储字体的上升高度。
  - **`int m_Descent = 0;`** : 存储字体的下降深度。
  - **`int m_ItalicAngle = 0;`** : 存储字体的斜体角度。
  - **`FX_RECT m_FontBBox;`** : 存储字体的边界框。

  ### 功能概述

  `CPDF_Font`类是PDFium库中用于管理和解析PDF文档中字体的核心类。它提供了以下功能：

  - **字体类型识别 * *：通过虚方法判断字体的具体类型（Type1、TrueType、Type3、CID等），并提供相应的类型转换接口。
  - **字符解析 * *：提供从字符码到字形索引、Unicode字符串的转换功能，支持多字节字符集和复杂字符映射。
  - **度量信息 * *：提供获取字体的边界框、上升高度、下降深度、斜体角度等度量信息的方法。
  - **备用字体管理 * *：支持备用字体的加载和使用，确保无法显示的字符能够找到合适的替代方案。
  - **Unicode兼容性 * *：支持Unicode编码，确保多语言文本的正确显示。
  - **资源管理 * *：管理字体的字典、文件流和备用字体，确保资源的正确加载和释放。
  - **回调机制 * *：通过`FormIface`和`FormFactoryIface`接口，支持Type3字体的动态加载和渲染。

  这些函数和成员变量共同工作，以实现对PDF文档中各种字体类型的高效管理和解析，确保文本的正确显示和渲染。`CPDF_Font`类是PDFium库中处理字体的核心组件之一，对于支持多种字体格式和字符集的PDF文档至关重要。
class CFX_DIBitmap;
class CPDF_CIDFont;
class CPDF_Document;
class CPDF_TrueTypeFont;
class CPDF_Type1Font;
class CPDF_Type3Char;
class CPDF_Type3Font;
class CPDF_ToUnicodeMap;
enum class FontEncoding;

class CPDF_Font : public Retainable, public Observable {
 public:
  // Callback mechanism for Type3 fonts to get pixels from forms.
  class FormIface {
   public:
    virtual ~FormIface() = default;

    virtual void ParseContentForType3Char(CPDF_Type3Char* pChar) = 0;
    virtual bool HasPageObjects() const = 0;
    virtual CFX_FloatRect CalcBoundingBox() const = 0;
    virtual std::optional<std::pair<RetainPtr<CFX_DIBitmap>, CFX_Matrix>>
    GetBitmapAndMatrixFromSoleImageOfForm() const = 0;
  };

  // Callback mechanism for Type3 fonts to get new forms from upper layers.
  class FormFactoryIface {
   public:
    virtual ~FormFactoryIface() = default;

    virtual std::unique_ptr<FormIface> CreateForm(
        CPDF_Document* pDocument,
        RetainPtr<CPDF_Dictionary> pPageResources,
        RetainPtr<CPDF_Stream> pFormStream) = 0;
  };

  static constexpr uint32_t kInvalidCharCode = static_cast<uint32_t>(-1);

  // |pFactory| only required for Type3 fonts.
  static RetainPtr<CPDF_Font> Create(CPDF_Document* pDoc,
                                     RetainPtr<CPDF_Dictionary> pFontDict,
                                     FormFactoryIface* pFactory);
  static RetainPtr<CPDF_Font> GetStockFont(CPDF_Document* pDoc,
                                           ByteStringView fontname);

  virtual bool IsType1Font() const;
  virtual bool IsTrueTypeFont() const;
  virtual bool IsType3Font() const;
  virtual bool IsCIDFont() const;
  virtual const CPDF_Type1Font* AsType1Font() const;
  virtual CPDF_Type1Font* AsType1Font();
  virtual const CPDF_TrueTypeFont* AsTrueTypeFont() const;
  virtual CPDF_TrueTypeFont* AsTrueTypeFont();
  virtual const CPDF_Type3Font* AsType3Font() const;
  virtual CPDF_Type3Font* AsType3Font();
  virtual const CPDF_CIDFont* AsCIDFont() const;
  virtual CPDF_CIDFont* AsCIDFont();

  virtual void WillBeDestroyed();
  virtual bool IsVertWriting() const;
  virtual bool IsUnicodeCompatible() const = 0;
  virtual uint32_t GetNextChar(ByteStringView pString, size_t* pOffset) const;
  virtual size_t CountChar(ByteStringView pString) const;
  virtual void AppendChar(ByteString* buf, uint32_t charcode) const;
  virtual int GlyphFromCharCode(uint32_t charcode, bool* pVertGlyph) = 0;
#if BUILDFLAG(IS_APPLE)
  virtual int GlyphFromCharCodeExt(uint32_t charcode);
#endif
  virtual WideString UnicodeFromCharCode(uint32_t charcode) const;
  virtual uint32_t CharCodeFromUnicode(wchar_t Unicode) const;
  virtual bool HasFontWidths() const;

  ByteString GetBaseFontName() const { return m_BaseFontName; }
  std::optional<FX_Charset> GetSubstFontCharset() const;
  bool IsEmbedded() const { return IsType3Font() || m_pFontFile != nullptr; }
  RetainPtr<CPDF_Dictionary> GetMutableFontDict() { return m_pFontDict; }
  RetainPtr<const CPDF_Dictionary> GetFontDict() const { return m_pFontDict; }
  uint32_t GetFontDictObjNum() const { return m_pFontDict->GetObjNum(); }
  bool FontDictIs(const CPDF_Dictionary* pThat) const {
    return m_pFontDict == pThat;
  }
  void ClearFontDict() { m_pFontDict = nullptr; }
  bool IsStandardFont() const;
  bool HasFace() const { return !!m_Font.GetFace(); }

  const FX_RECT& GetFontBBox() const { return m_FontBBox; }
  int GetTypeAscent() const { return m_Ascent; }
  int GetTypeDescent() const { return m_Descent; }
  int GetStringWidth(ByteStringView pString);
  uint32_t FallbackFontFromCharcode(uint32_t charcode);
  int FallbackGlyphFromCharcode(int fallbackFont, uint32_t charcode);
  int GetFontFlags() const { return m_Flags; }
  int GetItalicAngle() const { return m_ItalicAngle; }

  // Note that even when non-nullopt, the value may be outside the normal range
  // of [100, 900].
  std::optional<int> GetFontWeight() const;

  virtual int GetCharWidthF(uint32_t charcode) = 0;
  virtual FX_RECT GetCharBBox(uint32_t charcode) = 0;

  // Can return nullptr for stock Type1 fonts. Always returns non-null for other
  // font types.
  CPDF_Document* GetDocument() const { return m_pDocument; }

  CFX_Font* GetFont() { return &m_Font; }
  const CFX_Font* GetFont() const { return &m_Font; }

  CFX_Font* GetFontFallback(int position);

  const ByteString& GetResourceName() const { return m_ResourceName; }
  void SetResourceName(const ByteString& name) { m_ResourceName = name; }

 protected:
  CPDF_Font(CPDF_Document* pDocument, RetainPtr<CPDF_Dictionary> pFontDict);
  ~CPDF_Font() override;

  // Commonly used wrappers for UseTTCharmap().
  static bool UseTTCharmapMSUnicode(const RetainPtr<CFX_Face>& face) {
    return UseTTCharmap(face, 3, 1);
  }
  static bool UseTTCharmapMSSymbol(const RetainPtr<CFX_Face>& face) {
    return UseTTCharmap(face, 3, 0);
  }
  static bool UseTTCharmapMacRoman(const RetainPtr<CFX_Face>& face) {
    return UseTTCharmap(face, 1, 0);
  }
  static bool UseTTCharmap(const RetainPtr<CFX_Face>& face,
                           int platform_id,
                           int encoding_id);

  static const char* GetAdobeCharName(FontEncoding base_encoding,
                                      const std::vector<ByteString>& charnames,
                                      uint32_t charcode);

  virtual bool Load() = 0;

  void LoadUnicodeMap() const;  // logically const only.
  void LoadFontDescriptor(const CPDF_Dictionary* pFontDesc);
  void CheckFontMetrics();

  UnownedPtr<CPDF_Document> const m_pDocument;
  ByteString m_ResourceName;  // The resource name for this font.
  CFX_Font m_Font;
  std::vector<std::unique_ptr<CFX_Font>> m_FontFallbacks;
  RetainPtr<CPDF_StreamAcc> m_pFontFile;
  RetainPtr<CPDF_Dictionary> m_pFontDict;
  ByteString m_BaseFontName;
  mutable std::unique_ptr<CPDF_ToUnicodeMap> m_pToUnicodeMap;
  mutable bool m_bToUnicodeLoaded = false;
  bool m_bWillBeDestroyed = false;
  int m_Flags = 0;
  int m_StemV = 0;
  int m_Ascent = 0;
  int m_Descent = 0;
  int m_ItalicAngle = 0;
  FX_RECT m_FontBBox;
};

#endif  // CORE_FPDFAPI_FONT_CPDF_FONT_H_
